home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / clipper / ks94an.zip / DBCHOICE.HDR < prev    next >
Text File  |  1994-04-25  |  6KB  |  146 lines
  1. /******************************************************************************
  2.                  The Klipper Library, for CA-Clipper 5.x
  3.         Copyright (c), 1994, Wallace Information Systems Engineering
  4.  
  5. FUNCTION:
  6.  
  7. _DBChoice(cDBName, cDBIndex, cDBFdExp, cRetExpr, nTRow, nTCol, nBRow, nBCol,
  8. cColor, lBorder ) --> xExpression
  9.  
  10. PARAMETERS:
  11.  
  12. cDBName   = Name of Database File/Alias to Find/Open
  13. cDBIndex  = Index[es] to Open with File
  14. cDBFldExp = Field Expression to display
  15. cRetExpr  = Character expression evaluated as return value
  16.  
  17.  
  18. nTRow     = Window Coordinates including border
  19. nTCol     = (i.e., actual data window is one row/col
  20. nBRow     = inside these coordinates)
  21. nBCol     = " "
  22.  
  23.  
  24. cColor    = Color to Use for Window
  25. lBorder   = logical, TRUE = Draw Border, False = NO BORDER (DEFAULT)
  26. nBoxType  = Border type
  27.  
  28. SHORT:
  29.  
  30. Windowed database field picklist with return value from specified fields.
  31.  
  32. DESCRIPTION:
  33.  
  34. cDBName is either an explicit file name, or an alias of a currently
  35. open database file.  If not specified (NIL) then the current work area
  36. is assumed.  If no current work area, the function returns "" (empty()).
  37.  
  38. All open work areas are scanned to see if the file is currently open under
  39. the alias specified in cDBName. If the file is open already, either in
  40. the current or some other open work area with the ALIAS specified in
  41. cDBName, _DBChoice() switches to that area and proceeds.  If the alias is
  42. not found, then cDBName is used as an explicit file name to open. In
  43. either case, if the file is being used in, or attempting to use a file
  44. in, EXCLUSIVE mode, and that file cannot be accessed, then _DBChoice()
  45. returns NIL to indicate such.
  46.  
  47. If the database file is NOT open in any work area, it is opened in an
  48. unused work area, browsed, and closed upon exit at which time, the
  49. original work area (if any) is restored.  Thus, _DBChoice() will not
  50. change the status of your work areas or open files.  When it returns, all
  51. will be as it was before you made the function call.
  52.  
  53. If the specified database IS open, then cDBName must be the ALIAS that
  54. the database is open under.
  55.  
  56. If the specified database is NOT open, then the filename specified must
  57. either the filename only with the '.dbf' assumed.  The key is that if the
  58. file specified in cDBName is open then cDBName is going to be used in a
  59. SELECT statement and must select by ALIAS.  If the file is not open then
  60. the file is going to be opened with the name specified in cDBName.  Thus,
  61. if TEST.DBF is open and cDBName = 'TEST.DBF', then the select statement
  62. is going to attempt: SELECT TEST.DBF which will produce a runtime
  63. error because the ALIAS is TEST not TEST.DBF.
  64.  
  65.  
  66. It is safe, when using .DBF files to simply specify the FILENAME only.
  67. Thus the alias will select via a simple "SELECT cDBName", and if it is
  68. not open, the the "USE cDBName" will work satisfactorily.
  69.  
  70. Thus "SELECT TEST" and "USE TEST" will both work.
  71.  
  72. cDBIndex is an explicit index file name.  When _DBChoice() looks for
  73. the database file in the open work areas, if a file is found in any of
  74. those work areas and _DBChoice() switches to that area, then the
  75. indexes currently open in that area are used and cDBIndex is ignored.
  76. cDBIndex is only used when the requested database file is not open
  77. and _DBChoice() itself opens it and opens the index or indexes named
  78. in cDBIndex with it.  This is a character expression and may contain
  79. multiple indexes separated by a comma in the usual way.
  80.  
  81. cDBFldExp is a character expression containing a field name expression to
  82. be used to display the target database.
  83.  
  84.  
  85. NOTE:
  86.  
  87. The combined length of the fields specified in cDBFldExp (not the length
  88. of the expression field itself) cannot exceed the window coordinates passed.
  89.  
  90. cRetExpr is a character expression that is evaluated and applied at the
  91. time that _DBChoice() exits the function. This evaluation is made BEFORE
  92. the work area is closed or exited so that the expression may reference
  93. any fields in the record selected.  If cRetExpr is not specified,
  94. _then _DBChoice() returns the selected record's record number.
  95.  
  96.  
  97. The function will automatically fill the window such that the last
  98. physical record will reside on the last line of the window so that there
  99. will be no blank records displayed. Likewise, when paging up through
  100. the window, if there are not enough records to fill the window, the
  101. first physical record will reside in the first line of the window, again
  102. to prevent display of blank lines in the DBChoice() window. This is
  103. not possible however, if the number of records in the database is less
  104. than the number of lines in the display window.  In such a case, blank
  105. lines are inevitable.  For that reason, if a blank record is
  106. selected, _DBChoice() returns NIL to indicate such.
  107.  
  108. nTRow, nTCol, nBRow, nBCol are window coordinates.  By default, the
  109. actual working space will be one row and one character INSIDE
  110. these coordinates as a border is drawn AT these coordinates.  If
  111. these parameters are not specified, or are invalid (i.e., TOP row is
  112. greater than Bottom Row), default values are used.  The optional
  113. lBorder parameter modifies this (see below).
  114.  
  115. The default window is 00,00 to MaxRow(),MaxCol()
  116.  
  117. cColor is a character expression containing the color string to be used
  118. for the _DBChoice() window.  If you do not specifiy this parameter,
  119. the current colors are used as default.
  120.  
  121. lNo_Border is a logical.  If TRUE, then no border is drawn and the
  122. window coordinates are used for the actual data area.  If FALSE, then the
  123. data area is one ROW/COL INSIDE the window coordinates and the window
  124. border is drawn AT the window coordinates.  Also, if .f., Column Headers
  125. are draw as described.
  126.  
  127.  
  128. nBoxType is the type of border you wish to use.  _DBChoice() calls
  129. _PopBox() to accomplish this.  You may refer to _PopBox() for information
  130. on Box Types.
  131.  
  132. _DBChoice() presents a database for browse only, and evaluates an
  133. expression for a return value when ENTER is pressed.  If ESC is pressed,
  134. the expression is not evaluated and the function returns NIL.
  135.  
  136.  
  137. RETURNS: If no Expression is specified, a record number is returned.  If
  138. an expression is specified and is valid, the results of that evaluation
  139. are returned only when ENTER is pressed.  ESC returns NIL.
  140.  
  141. EXAMPLE:
  142.  
  143.  
  144.  
  145. ******************************************************************************/
  146.